home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 26 / Cream of the Crop 26.iso / program / p063b9s.zip / UNIT / MAXCOMM.PAS < prev    next >
Pascal/Delphi Source File  |  1997-01-29  |  15KB  |  430 lines
  1. UNIT MaxComm;
  2.  
  3. {$L MAXCOMM.LIB}
  4.  
  5. INTERFACE
  6. {
  7.  *  Header file for COMM.DLL,  a high performance multithreading
  8.  *  library for OS/2 serial port i/o.
  9.  *
  10.  *  Copyright (C) 1990, 1991 A:WARE Inc.  All rights reserved.
  11.  *
  12.  * Comm.h, MaxComm.lib, and MaxComm.dll may be used and distributed freely for
  13.  * non-profit use, provided that they are distributed together and
  14.  * are not modified in any way. This means that any program that uses
  15.  * them has to be free, unless prior written persmission from A:WARE
  16.  * Inc. states otherwise.
  17.  *
  18.  * Inclusion with a for-profit/commercial program requires that you
  19.  * purchase the source code for MaxComm.dll.  No royalties.
  20.  * The cost is US$199.
  21.  *
  22.  * Contact A:WARE Inc:
  23.  *
  24.  * 6056 Cayeswood Ct, Ste 100
  25.  * Mississauga, Ontario
  26.  * Canada
  27.  * L5V 1B1
  28.  *
  29.  * (416)858-3222.
  30.  *
  31.  * Author: Peter Fitzsimmons, March 1990.
  32.  }
  33.  
  34. { NB:  To create a "maxcomm.lib" to link with,  do this:
  35.  
  36.       IMPLIB Maxcomm.lib Maxcomm.Dll
  37.  
  38.   (assuming maxcomm.dll is in the current directory
  39.  
  40.  }
  41.  
  42. {
  43.  * include os2.h or os2def.h before this file.
  44.  *
  45.  }
  46. {#ifndef APIENTRY
  47. #include <os2def.h>
  48. #include <bsedos.h>
  49. #endif}
  50.  
  51. USES OS2Def, OS2Base, OS2PMApi;
  52.  
  53. TYPE
  54.   SHORT = Integer;
  55.  
  56.   HComm = SHandle;
  57.  
  58. {#define COMMAPI  pascal far}
  59.  
  60.  
  61. {
  62.  * open comm device.  return 0 if successful,  OS/2 error if not.
  63.  *
  64.  * This function (or ComHRegister()) must be called before any
  65.  * other Com() function.
  66.  *
  67.  * Do not use this function if the port handle has been inherited from
  68.  * another process (use ComHRegister() instead).
  69.  *
  70.  * The comm handle (placed in pHcomm) is not a file handle,  and should
  71.  * not be used by Dos() functions.  If the file handle to the port is
  72.  * needed (to pass to a child process),  use the ComGetFH() function.
  73.  *
  74.  * If RxBufSize and/or TxBufSize are/is zero,  a default size is used.
  75.  *
  76.  
  77.   When using COM0x.SYS,  the default buffer size is the same as the
  78.   buffer size used by COM0x.SYS.  For Tx, this is the optimum size
  79.   to keep COM0x.SYS busy.  A buffer larger than this will not gain
  80.   any extra performance.  Therefore, the common urge to make the
  81.   transmit buffer large will not have the desired effect.  If there
  82.   was some way to make the REAL transmit buffer (the one in
  83.   COM0x.SYS) larger,  performance gains WOULD be seen,  but there is
  84.   no way to do this unless you have the source code for COM0x.SYS.
  85.   If you DO have the source (in the DDK), and you increase the
  86.   buffer sizes, use 0 for the XxBufSize and ComOpen will use your
  87.   larger buffers (ComOpen/Register uses the standard IOCTL call to
  88.   query the buffer sizes).
  89.  
  90.   RxBufSize, on the otherhand, does not affect performance of any
  91.   functions in the Com() module.  To avoid overflows however,  you
  92.   should set this to at least the size of the COM0x.SYS Rx buffer,
  93.   or use 0 so the default size if selected.  When the Rx buffer gets
  94.   full,  the speaker will sound (DosBeep(200, 10)).  There are two
  95.   solutions to this problem:  Make the Rx buffer larger (preferred),
  96.   or raise the priority of the thread calling ComRead()/ComGetc().
  97.  
  98.   All threads created by comm.dll run at the default priority. Since
  99.   com0?.sys is interrupt driven,  Reading/Writing to it at a high
  100.   priorty does not improve anything.  If the Rx thread is starved
  101.   for such a long time that com0?.sys buffer gets full,  it means
  102.   some other process on your computer is badly behaved (IT is
  103.   problably running at Time Critical class when it shouldn't be).
  104.   There are four ways to solve this (in order of preference):
  105.  
  106.   1) Insert DosSleep(1L) in the polling loops that are guilty (this
  107.   assumes you have source code), and/or have it run at NORMAL
  108.   priority class.
  109.  
  110.   2) decrease MAXWAIT in config.sys.
  111.  
  112.   3) Prior to calling ComOpen/ComHRegister, raise the priorty of the
  113.   current thread (or of the whole process).  The Rx/Tx threads will
  114.   inherhit this priority.
  115.  
  116.   4) set PRIORITY=ABSOLUTE in config.sys.
  117.  
  118.  
  119.   FYI:  OS/2 1.2 uses a default size of 1024 bytes for Rx, and 128
  120.         bytes for Tx.
  121.  
  122.  *
  123.  *
  124.  }
  125. FUNCTION ComOpen(PortName: PChar; VAR Comm: HComm;  { pointer to var for Comm handle }
  126.                  RxBufSize: USHORT;                 { desired size of Receive queue}
  127.                  TxBufSize: USHORT): USHORT;        { desired size of Transmit queue }
  128.  
  129. {
  130.  * ComHRegister():  Register a comm handle opened by another process.
  131.  *
  132.  * This function (or ComOpen()) must be called before any
  133.  * other Com() function.
  134.  }
  135. FUNCTION ComHRegister(hf: HFILE;
  136.                       VAR comm: HCOMM;             { pointer to var for Comm handle }
  137.                       RxBufSize: USHORT;           { desired size of receive queue}
  138.                       TxBufSize: USHORT): USHORT;  { desired size of xmit queue }
  139.  
  140.  
  141. { ComClose():  Close and/or DeRegister comm handle.
  142.  *
  143.  * This function will not DosClose() the handle if the handle was not
  144.  * opened by this process with ComOpen() (ie: If ComHRegister() was used,
  145.  * ComClose() will not DosClose() the handle.  ComClose() must still be
  146.  * called though).
  147.  }
  148. FUNCTION ComClose(comm: HCOMM): USHORT;
  149.  
  150.  
  151. {
  152.  * return TRUE if the device (comx, named pipe, etc) is considered
  153.  * in an "Online" state.
  154.  }
  155. FUNCTION ComIsOnline(comm: HCOMM): USHORT;
  156.  
  157. {
  158.  * ComWrite(): Place many bytes in output queue.
  159.  *
  160.  * This function does not return until all of the bytes have been
  161.  * placed in the output queue,  or an error occurs.
  162.  *
  163.  * If the device becomes offline while this function is waiting for
  164.  * queue space, and the watchdog feature is enabled (see
  165.  * ComWatchDog()),  this function returns before completion.
  166.  *
  167.  }
  168. FUNCTION ComWrite(hc: HCOMM;                          { file handle                   }
  169.                   VAR pvBuf;                          { pointer to buffer             }
  170.                   cbBuf: USHORT): USHORT;             { number of bytes to write      }
  171.  
  172.  
  173. {
  174.  * ComRead(): Read many bytes from input queue.
  175.  *
  176.  * This function will copy bytes from the input queue to pvBuf,
  177.  * until the input queue is empty, or 'cbBuf' bytes have been copied.
  178.  *
  179.  *
  180.  }
  181. FUNCTION ComRead(hc: HCOMM;                     { file handle                 }
  182.                  VAR pvBuf;                     { pointer to buffer           }
  183.                  cbBuf: USHORT;                 { maximum bytes to read       }
  184.                  VAR pcbBytesRead): USHORT;     { pointer to variable receiving
  185.                                                   byte count }
  186.  
  187. {
  188.  * ComGetc() : return next byte in input queue,  or -1 if there is none.
  189.  }
  190. FUNCTION ComGetc(hc: HCOMM): SHORT;
  191.  
  192. {
  193.  * ComPeek():  the same as ComGetc(),  but the character is left in the
  194.  * input queue.
  195.  }
  196. FUNCTION ComPeek(hc: HCOMM): SHORT;
  197.  
  198. {
  199.  * ComPutc():  Place one byte in output queue.  This function does not
  200.  * return until the byte is placed in the output queue, or an error occurs.
  201.  *
  202.  * If the device becomes offline while this function is waiting for
  203.  * queue space, and the watchdog feature is enabled (see
  204.  * ComWatchDog()),  this function returns before completion.
  205.  }
  206. FUNCTION ComPutc(hc: HCOMM; c: SHORT): USHORT;
  207.  
  208. {
  209.  * ComRxWait():  Wait for something to be placed into the input queue.
  210.  *
  211.  * If lTimeOut is -1L,  wait forever.  Otherwise, lTimeOut is the
  212.  * number of milliseconds to wait (or 0) before returning a timeout
  213.  * error (ERROR_SEM_TIMEOUT).
  214.  *
  215.  * If the device becomes offline while this function is waiting, and
  216.  * the watchdog feature is enabled (see ComWatchDog()),  this
  217.  * function returns before completion.
  218.  *
  219.  }
  220. FUNCTION ComRxWait(hc: HCOMM; lTimeOut: LONG): USHORT;
  221.  
  222. {
  223.  * ComTxWait():  Wait for output queue to empty.
  224.  *
  225.  * If lTimeOut is -1L,  wait forever.  Otherwise, lTimeOut is the
  226.  * number of milliseconds to wait (or 0) before returning a timeout
  227.  * error (ERROR_SEM_TIMEOUT).
  228.  *
  229.  * If the device becomes offline while this function is waiting, and
  230.  * the watchdog feature is enabled (see ComWatchDog()),  this
  231.  * function returns before completion.
  232.  }
  233. FUNCTION ComTxWait(hc: HCOMM; lTimeOut: LONG): USHORT;
  234.  
  235.  
  236. {
  237.  * return number of bytes in input queue.
  238.  *
  239.  }
  240. FUNCTION ComInCount(hc: HCOMM): USHORT;
  241.  
  242. {
  243.  * return number of bytes in output queue.
  244.  *
  245.  }
  246. FUNCTION ComOutCount(hc: HCOMM): USHORT;
  247.  
  248. {
  249.  * return space in output queue.
  250.  *
  251.  }
  252. FUNCTION ComOutSpace(hc: HCOMM): USHORT;
  253.  
  254. CONST
  255.   COMM_PURGE_RX  = 1;
  256.   COMM_PURGE_TX  = 2;
  257.   COMM_PURGE_ALL = (COMM_PURGE_RX OR COMM_PURGE_TX);
  258. {
  259.  * ComPurge():  Purge (discard) i/o queue(s).
  260.  *
  261.  *  Where fsWhich is a combination of :
  262.  *           COMM_PURGE_RX      Purge input queue.
  263.  *
  264.  *           COMM_PURGE_TX      Purge output queue.
  265.  }
  266. FUNCTION ComPurge(hc: HCOMM; fsWhich: SHORT): USHORT;
  267.  
  268.  
  269. {
  270.  * ComPause():
  271.  *
  272.  * This function causes the Rx and Tx threads to end, after all
  273.  * Tx activity has ended.  Any bytes still in the Rx queue are
  274.  * purged.  After calling this function,  it is safe for other
  275.  * processes to use the comm port file handle (see ComGetFH()).
  276.  *
  277.  }
  278. FUNCTION ComPause(hc: HCOMM): USHORT;
  279.  
  280. {
  281.  * ComResume():
  282.  *
  283.  * This function creates new Rx and Tx threads,  and resets the state
  284.  * of the comm port to what is was when ComPause() was called.
  285.  *
  286.  * It is an error to call this function without calling ComPause().
  287.  *
  288.  }
  289. FUNCTION ComResume(hc: HCOMM): USHORT;
  290.  
  291. {
  292.  *
  293.  * ComGetFH():  get the file handle (HFILE) the comm module is
  294.  * using.
  295.  *
  296.  * If the comm routines were initialized with ComHRegister(),  the
  297.  * handle returned by this function will be the same handle passed
  298.  * to ComHRegister().
  299.  *
  300.  * NOTE: Programs must not use this handle with any file system
  301.  * calls (DosRead, DosWrite, DosClose, etc).  It may be used with
  302.  * DosDevIOCTL() to query device dependant info.
  303.  *
  304.  * The intended use for this function is so that one process can
  305.  * pass the file handle to another process.  Don't forget to
  306.  * call ComPause() before spawning another process that uses the comm
  307.  * port.
  308.  }
  309. FUNCTION ComGetFH(hc: HCOMM): HFILE;
  310.  
  311. {
  312.  * ComWatchDog():  Enable/disable the "online" watchdog.
  313.  *
  314.  * When the watchdog is enabled,  and the state of the comm handle
  315.  * is no longer "online" (in the case of a modem,  the carrier has dropped),
  316.  * any Com functions that are blocked (ComRxWait, ComTxWait) become
  317.  * unblocked,  within the period specified by the "Seconds" paramater.
  318.  *
  319.  * It is up to the application to notice that the device is no longer
  320.  * online,  after the blocked Com function returns.
  321.  *
  322.  * Obviously,  one must remember to disable the watchdog feature between
  323.  * phone calls.
  324.  *
  325.  * When a device is first initialized by the comm moduel (via ComOpen() or
  326.  * ComHRegister()) the watchdog feature is disabled.
  327.  *
  328.  * The "Seconds" paramater is ignored unless "OnOff" is TRUE.
  329.  *
  330.  * If "OnOff" is TRUE,  and "Seconds" is 0,  the current watchdog period
  331.  * is used.  When first initialized,  the watchdog period is 3 seconds.
  332.  }
  333. FUNCTION ComWatchDog(hc: HCOMM; OnOff: BOOL; Seconds: USHORT): USHORT;
  334.  
  335. {******************************************************************
  336.  *                                                                 *
  337.  * Thus far, all functions listed are applicable to many           *
  338.  * device types,  including named pipes.  The 3 functions          *
  339.  * that follow, however, are specific to COM0x.SYS (rs232c ports). *
  340.  *                                                                 *
  341.  ******************************************************************}
  342.  
  343. {
  344.  * Get/Set DBC.  See os/2 docs on "DCBINFO", used in a
  345.  * DosIOCTL(ASYNC_GETDCBINFO) call (ioctl category 1, function 73h)
  346.  *
  347.  *
  348.  * NOTE: ComSetDCB() ignores bits 0, 1 and 2 of the "fbTimeout"
  349.  * field of the DCBINFO structure. (if you are using the IBM toolkit,
  350.  * this is called "flags3" of the DCB).  These bits control the type
  351.  * of read timeout processing, and write timeout processing that the
  352.  * com01.sys device driver uses.  The Com() api insists that
  353.  * "write infinite timeout processing" NOT be enabled,  and
  354.  * "Wait-for-something read timeout processing" be in effect, so this
  355.  * function overrides the above mentioned bits to ensure this.
  356.  *
  357.  }
  358. {#ifdef IOCTL_ASYNC}
  359. FUNCTION ComGetDCB(hc: HCOMM; pdbc: PDCBINFO): USHORT;
  360. FUNCTION ComSetDCB(hc: HCOMM; pdcb: PDCBINFO): USHORT;
  361. {#endif}
  362.  
  363. FUNCTION ComSetBaudRate(hcomm: HCOMM;
  364.                         bps: LONG;
  365.                         parity: CHAR;
  366.                         databits: USHORT;
  367.                         stopbits: USHORT): USHORT;
  368.  
  369.  
  370.  
  371. {#ifdef INCL_WININCLUDED}
  372. { First new function added since version 1.00:
  373.  *
  374.  * ComRxPostMsg() -- register a PM window handle. When data is
  375.  * available,  a message will be Posted to it.
  376.  *
  377.  * Be sure to deregister the window before it is destroyed.  Do
  378.  * this by passing 0 for the window handle (hwnd).
  379.  *
  380.  *
  381.  *  hwnd = Window handle or zero.
  382.  *  msg  = message to post (WM_USER for example)
  383.  *  mp1  = user defined (passed unchanged to hwnd)
  384.  *  mp2  = user defined (passed unchanged to hwnd)
  385.  *
  386.  *
  387.  * NOTES:  When the message is posted, it is advisory only.  The message
  388.  *         does not need to be processed.  The message will be posted
  389.  *         again when more data arrives.  The receiver should call
  390.  *         ComRead() to get the data when convenient.
  391.  *
  392.  *
  393.  * Returns:        0: success.
  394.  *          non-zero: OS/2 error
  395.  }
  396.  
  397. FUNCTION ComRxPostMsg(hcomm: HCOMM; wnd: HWND; msg: USHORT;
  398.                       mp1: MPARAM; mp2: MPARAM): USHORT;
  399.  
  400. {#endif}
  401.  
  402. IMPLEMENTATION
  403.  
  404.   FUNCTION ComOpen;        EXTERNAL;
  405.   FUNCTION ComHRegister;   EXTERNAL;
  406.   FUNCTION ComClose;       EXTERNAL;
  407.   FUNCTION ComIsOnline;    EXTERNAL;
  408.   FUNCTION ComWrite;       EXTERNAL;
  409.   FUNCTION ComRead;        EXTERNAL;
  410.   FUNCTION ComGetc;        EXTERNAL;
  411.   FUNCTION ComPeek;        EXTERNAL;
  412.   FUNCTION ComPutc;        EXTERNAL;
  413.   FUNCTION ComRxWait;      EXTERNAL;
  414.   FUNCTION ComTxWait;      EXTERNAL;
  415.   FUNCTION ComInCount;     EXTERNAL;
  416.   FUNCTION ComOutCount;    EXTERNAL;
  417.   FUNCTION ComOutSpace;    EXTERNAL;
  418.   FUNCTION ComPurge;       EXTERNAL;
  419.   FUNCTION ComPause;       EXTERNAL;
  420.   FUNCTION ComResume;      EXTERNAL;
  421.   FUNCTION ComGetFH;       EXTERNAL;
  422.   FUNCTION ComWatchDog;    EXTERNAL;
  423.   FUNCTION ComGetDCB;      EXTERNAL;
  424.   FUNCTION ComSetDCB;      EXTERNAL;
  425.   FUNCTION ComSetBaudRate; EXTERNAL;
  426.   FUNCTION ComRxPostMsg;   EXTERNAL;
  427.  
  428. END.
  429.  
  430.